home *** CD-ROM | disk | FTP | other *** search
- /*
- File: DiskLog.h
-
- Copyright: © 1991-1994 by Apple Computer, Inc.
- All rights reserved.
-
- Part of the AOCE Sample SMSAM Package. Consult the license
- which came with this software for your specific legal rights.
-
- */
-
-
-
- #ifndef __DISKLOG__
- #define __DISKLOG__
-
- #ifndef __TYPES__
- #include "Types.h"
- #endif
-
- #ifndef __DISKENTRY__
- #include "DiskEntry.h"
- #endif
-
- #ifndef __DIRECTOBJECT__
- #include "DirectObject.h"
- #endif
-
- #pragma push
- #pragma segment DiskLog
-
- // forward declarations
- class ostream;
- class TFileSpec;
- class TPurgeCriteria;
- class TSemaphore;
- class TAbstractFile;
- class TLogEntry;
-
- /*============================================================================
-
- TDiskLog is a class which represents a storage place for entries, objects
- which contain information which must be persistent and stored in on disk.
- The file which contains the log entries is determined by the TFileSpec
- object passed to the log on instantiation.
-
- A log contains 1..CountEntries() entries, and each entry within a log
- is assigned a unique serial number within that log. Entries added to
- logs must be subclasses of TLogEntry (see LogEntry.h). The maxmimum
- number of entries which can be placed in a log is only limited by the
- amount of free disk space available.
-
- Entries are placed in a log using AddEntry(). However, the caller still
- owns the entry object being added. An image of the entry is immediately
- written to the log’s file. The entry is also assigned a new EntryID.
-
- Entries can be retrieved from a log using CreateEntry() which requires
- the user to supply an index of the desired entry. The caller owns the
- object returned by CreateEntry(). TDiskLogEnumerator and TDiskLogIterator are
- classes which perform advanced mult-user access to log contents.
-
- A log also has the capability for purging entries according to a
- TPurgeCriteria object which specifies the EntryIndex of the latest entry
- which can be purged.
-
- ----------------------------------------------------------------------------*/
-
-
- typedef unsigned long EntryIndex;
- typedef unsigned short FormatVersion;
- typedef long EntryOffset;
-
- typedef struct LogHeader
- {
- FormatVersion fFormatVersion; // hiword is min entry size, loword is header size
- unsigned long fEntryCount;
- EntryID fFirstEntryID;
- EntryOffset fLastEntryOffset;
- EntryOffset fNewEntryOffset;
- EntryIndex fCurrentEntryIndex;
- EntryOffset fCurrentEntryOffset;
- } LogHeader;
-
-
- class TDiskLog : public TDirectObject
- {
- public:
-
- enum LogPermission { kRewrite, kAppend, kRead, kNoneOfTheAbove };
-
- static const EntryIndex kInvalidIndex;
-
- TDiskLog ( const TFileSpec&, TPurgeCriteria* = nil );
- virtual ~TDiskLog ();
-
- // log control
-
- virtual Boolean Open ( LogPermission = kAppend );
- virtual Boolean Close ();
- virtual Boolean Delete ();
-
- // entry access
-
- virtual Boolean AddEntry ( TLogEntry& );
- virtual TLogEntry* CreateEntry ( EntryIndex );
- virtual Boolean RemoveUntil ( EntryIndex );
- EntryIndex CountEntries ();
- Boolean IsValidIndex ( EntryIndex );
-
- // wrapping criteria
-
- virtual void AdoptPurgeCriteria ( TPurgeCriteria* );
- virtual TPurgeCriteria* OrphanPurgeCriteria ();
- const TPurgeCriteria* GetPurgeCriteria () const;
-
- // file typing
-
- virtual OSType GetLogFileCreator () const;
- virtual OSType GetLogFileType () const;
-
- /***********************************|****************************************/
-
- // the following methods are for protected use and/or debugging only
-
- #ifndef debug
- protected:
- #endif
-
- static void DumpLog ( ostream& );
- static void DumpLog ( ostream&, const FSSpec& );
-
- virtual Boolean InvariantCheck ( ostream& ) const;
- virtual ostream& operator >> ( ostream& ) const;
-
-
- // interface for reading and writing entries
-
- // these handle the entire internal file format
-
- virtual Boolean WriteNewEntry ( TLogEntry& );
- virtual Boolean FlattenFromCurrentMark ( TLogEntry& );
- virtual TLogEntry* ResurrectFromCurrentMark ();
- virtual TLogEntry* ScavengeFromMark ();
- virtual Boolean HandleError ( OSErr, const char* file = nil, unsigned long line = 0 );
-
- // methods for directing to entries in the file
-
- virtual Boolean MoveToValidEntry ( EntryIndex );
- virtual Boolean MoveToNextEntry ();
- virtual Boolean MoveToPreviousEntry ();
-
- // by default, the following two routines handle polymorphic entries
- // override to handle more compact entry storage for monomorphic entry logs
-
- virtual Boolean WriteEntryReconstructInfoAtCurrentMark ( const TLogEntry& );
- virtual TLogEntry* ReconstructEntryFromInfoAtCurrentMark ();
-
- virtual Boolean WritePolymorphicEntryReconstructInfoAtCurrentMark ( const TLogEntry& );
- virtual TLogEntry* ReconstructPolymorphicEntryFromInfoAtCurrentMark ();
-
- // these are general purpose
-
- virtual Boolean ValidateDiskContents ( ostream& );
- virtual Boolean EnsureUsabilityOnceOpen ( LogPermission );
-
- // this is loaded to and dumped from the start of the log file
-
- virtual Boolean LoadHeaderInfo ();
- virtual Boolean DumpHeaderInfo ();
- virtual Boolean ValidateHeaderContents ( const struct LogHeader&, unsigned long fileEnd ) const;
- virtual void InitializeHeaderValues ( struct LogHeader& ) const;
-
- virtual FormatVersion GetFormatVersion () const;
- virtual Boolean HandleUnexpectedVersion ( FormatVersion );
-
- EntryIndex MapToIndex ( EntryID ) const;
- EntryID MapToID ( EntryIndex ) const;
- Boolean IsValidOffset ( EntryOffset ) const;
-
- private: TDiskLog ( const TDiskLog& ); // operation not defined
- TDiskLog& operator = ( const TDiskLog& ); // operation not defined
-
- LogHeader fHeader;
-
- // this is runtime-only info
-
- TAbstractFile* fFile;
- TPurgeCriteria* fCriteria;
- LogPermission fPermission;
-
- friend class TDiskLogEnumerator;
- friend class TDiskLogIterator;
- };
-
- /***********************************|****************************************/
-
- class TDiskLogEnumerator : public TDirectObject
- {
- public: TDiskLogEnumerator ( TDiskLog& );
- virtual ~TDiskLogEnumerator ();
-
- EntryIndex CountEntries () const;
-
- const TLogEntry* GetEntryByIndex ( EntryIndex );
- TLogEntry* AdoptEntryByIndex ( EntryIndex );
-
- const TLogEntry* GetEntryByID ( EntryID );
- TLogEntry* AdoptEntryByID ( EntryID );
- #if debug
- virtual Boolean InvariantCheck ( ostream& ) const;
- virtual ostream& operator >> ( ostream& ) const;
- #endif
-
- protected: TDiskLogEnumerator (); // operation not defined
- TDiskLogEnumerator& operator = ( const TDiskLogEnumerator& ); // operation not defined
-
- TDiskLog& fLog;
- TLogEntry* fEntryCache;
- EntryID fFirstEntryID;
- };
-
- /***********************************|****************************************/
-
- class TDiskLogIterator : public TDirectObject
- {
- public: TDiskLogIterator ( TDiskLog& );
- virtual ~TDiskLogIterator ();
-
- const TLogEntry* GetFirstEntry ();
- TLogEntry* AdoptFirstEntry ();
-
- const TLogEntry* GetNextEntry ();
- TLogEntry* AdoptNextEntry ();
-
- const TLogEntry* GetLastEntry ();
- TLogEntry* AdoptLastEntry ();
-
- const TLogEntry* GetPreviousEntry ();
- TLogEntry* AdoptPreviousEntry ();
- #if debug
- virtual Boolean InvariantCheck ( ostream& ) const;
- virtual ostream& operator >> ( ostream& ) const;
- #endif
-
- private: TDiskLogIterator ( const TDiskLogIterator& ); // operation not defined
- TDiskLogIterator& operator = ( const TDiskLogIterator& ); // operation not defined
-
- TDiskLog& fLog;
- TDiskLogEnumerator fImplementation;
- EntryIndex fNextIndex;
- };
-
- /***********************************|****************************************/
-
- class TPurgeCriteria
- {
- public:
- virtual EntryIndex AdviseRemoveUntil ( const TDiskLog& ) = 0;
- };
-
- /***********************************|****************************************/
-
- class TFileSizePurgeCriteria : public TPurgeCriteria
- {
- public:
- virtual EntryIndex AdviseRemoveUntil ( const TDiskLog& );
- };
-
- /***********************************|****************************************/
-
- class TEntryCountCriteria : public TPurgeCriteria
- {
- public:
- virtual EntryIndex AdviseRemoveUntil ( const TDiskLog& );
- };
-
- /***********************************|****************************************/
- /***********************************|****************************************/
-
- #ifndef debug
-
- // if we are not debugging, we implement checking as a trivial no-op inline
- // functions having zero overhead for production code; that way our clients
- // don’t have to #ifdef debug any of their code (and we don’t have to either)
-
- inline Boolean TDiskLog::InvariantCheck ( ostream& ) const { return true; }
-
- #if debug
- inline Boolean TDiskLogEnumerator::InvariantCheck ( ostream& ) const { return true; }
- inline Boolean TDiskLogIterator::InvariantCheck ( ostream& ) const { return true; }
- #endif
-
- #endif // debug
-
- /***********************************|****************************************/
-
- inline EntryIndex TDiskLog::CountEntries () { return fHeader.fEntryCount; }
- inline Boolean TDiskLog::IsValidIndex ( EntryIndex index ) { return ( index > kInvalidIndex ) && ( index <= fHeader.fEntryCount ); }
- inline EntryID TDiskLog::MapToID ( EntryIndex index ) const { return fHeader.fFirstEntryID + ( index - 1 ); }
- inline EntryIndex TDiskLog::MapToIndex ( EntryID id ) const { return ( id - fHeader.fFirstEntryID ) + 1; }
- inline const TPurgeCriteria* TDiskLog::GetPurgeCriteria () const { return fCriteria; }
- inline EntryIndex TDiskLogEnumerator::CountEntries () const { return fLog.CountEntries (); }
- inline TLogEntry* TDiskLogEnumerator::AdoptEntryByIndex ( EntryIndex index ) { return fLog.CreateEntry ( index ); }
- inline const TLogEntry* TDiskLogEnumerator::GetEntryByID ( EntryID id ) { return GetEntryByIndex ( id - fFirstEntryID + 1 ); }
- inline TLogEntry* TDiskLogEnumerator::AdoptEntryByID ( EntryID id ) { return AdoptEntryByIndex ( id - fFirstEntryID + 1 ); }
-
- /***********************************|****************************************/
-
- #pragma pop
-
- #endif // __DISKLOG__
-